All additions are at the bottom. That way, you can start reading the first time you get this and keep going in chronological order. Keep in mind that I will NOT change previously-written documentation to reflect changes. In other words, read THE WHOLE THING before trying to use this.
NO PORTION OF THIS CODE MAY BE USED IN ANY COMMERCIAL OR SOLD PRODUCT WITHOUT THE EXPRESSED, WRITTEN CONSENT OF ITS AUTHOR.
WARNING: This is something I threw together in a couple of hours; it's an example, meant to help a few novices who asked for it and to encourage discussion…in other words, don't bash my code, dammit. These docs took me about as long as the code…
This is a bunch of 4D code that simulates the 4D Choice List. As far as the user is concerned, it looks just like the usual "popup" Choice List (that window that appears in the upper right hand corner when they click on a field which has "choices") but, since it's really 4D code, you can do whatever you want while you're in there.
Why is it 4D code and not an external?
======================================
Because I'm not as proficient in C as I am in 4D, that's why, Mr. All High And Mighty External Geek.
Why did I do this in the first place?
=====================================
Someone asked if it was possible. That's a great way to get me to do utterly ridiculous things…ask if it's possible. I did this in response to a request on the Internet; several people asked for it. Rather than send it to whomever asks for it, I thought that it would be interesting to distribute and see what people could do to improve on its ideas.
Anyway, it's easy to put up the right little dialog on the screen with a scrollable array which will look just like the usual choice list dialog. But what about when the user types a letter? They should jump to the first item with that letter (which 4D doesn't do right, in my humble opinion…to see why, put an UNALPHABETIZED array in a choice list and type a letter which is after its predecessor…for example, if "alpha" follows "bat" in a list, typing "a" will accomplish nothing because 4D assumes that as soon as it hits "b", it must have already passed "a"…correct 99% of the time, but I don't always find that a list should be alphabetized). How do we do that letter-selection?
First, I thought that I would do this via a DIALOG command which had the scrollable area and the two buttons. When you typed a character, I would intercept it with ON EVENT CALL and act on it. But, of course, I realized that wouldn't work because DIALOGS don't return events to ON EVENT CALL when a character is typed.
Next, I thought that I would do a DISPLAY RECORD, which would give me events. This, of course, sucked because the beachball spun the entire time.
I was faced with a dilemma…I couldn't think of any way to simultaneously get events AND not run code, which is, of course, contradictory.
Beyond the view of the user is a group of invisible buttons. There are two rows of 26, a single button, and three more in the last row. The first row contains buttons whose hot keys are "A" through "Z". The second row is buttons whose hot keys are Command-A through Command-Z (we'll deal with this later). The third row contains a button for "Escape" (explained later). The last row contains buttons for "Enter", "Return" and "Command-Period".
When we're in the layout and the user types an "a" (or, for that matter, a Shift-A…or even an Option-A [4D anomaly]), the "a" button gets executed. Its script calls a procedure, telling it that just an "a" was pressed. This procedure then jumps to the NEXT item in the list which begins with an "a" (or "A"). This means that even after one item is chosen, another may be chosen (I could type "a", which would jump to the first item starting with "a", then I could type "d" and jump to the first "d"). The "jump" will never go backwards, though it would be trivial to implement this. Note that CCLD doesn't assume that the list is alphabetized. If no item is found, the original selection is left untouched (you could beep at that point if you wished to indicate that no item met the last-typed letter).
Note that I haven't implemented multiple-letter selections. You can't type "al" to jump past "abandon" to "alpha". This probably wouldn't be terribly difficult to implement but it probably would not work uncompiled or on slow Macs. Note also that all I have created for you are buttons for the a-z keys; there are no numbers or symbols. You can VERY easily do this, though. And, if people actually want me to, I'll do it for you.
For what more could we possibly ask?
====================================
What's the Command-letter row for? I figured that if all this did was duplicate the 4D Choice List Window then there would be no point. So, as an example of the types of things which you might want to do, I implemented sub-selections. If a user types Command-letter, all items in the list beginning with that letter will be extracted out into their own "sublist" and displayed in the window. For example, if we started with:
animal
alabama
banana
frog
abraham lincoln
terrible
and the user typed Command-A, the choice list would show only:
animal
alabama
abraham lincoln
When the user is dealing with huge selections, this can be a nice way to cut down the amount of data being viewed. If the user decides that they want the original list displayed, they can type Escape, which returns the list to normal.
$ChosenItem (returned to you) will contain one of three things:
Null: this means that the user typed Command-Period.
Char(1) plus a negative number (like "-1"): this tells you that the user clicked one of the two buttons displayed in the dialog. The one on the left is button #1, the one on the right is button #2.
something: if you don't get either of the two above things, you will get the actual text of the item the user selected.
ShowChoiceList accepts five parameters:
#1: [string] the title of the choice list window (another advantage over the default 4D choice list window)
#2: [string] the text for button #1 (another improvement)
#3: [integer] either a 1 (which means that the button is enabled) or some other number (which means that it's disabled…"0" is fine and logical but anything other than "1" disables the button).
#4: [string] the text for button #2
#5: [integer] see #3 above but this is for button #2
The choice list window will automatically be placed exactly where the normal 4D window would be.
What are those two buttons for?
===============================
Whatever you want. I simply close the CCLD window and pass back to you the button number and leave it up to you to handle it however you want. I didn't put function-dedicated scripts behind them and I suggest that you don't, either. If you call ShowChoiceList and get back a response that the user clicked one of them, do something. But putting a specific script behind them would mean that you ALWAYS do the same thing; if that's the case, you could do without the need to name the en/disable the buttons. If that's fine for you, so be it.
So, what's next?
================
That depends on you guys. I'm tossing this out there to see what sorts of things you can think of to add to it. I have already implemented a feature whereby the list will automatically expand to double the usual size if there are more items that can be displayed in the default size without scrolling (some users hate to scroll). I'll upload this additional stuff if anyone cares…
There's one example (already done, though). What else can you think of? I had originally planned on just mailing this to the five people on the Internet who had asked for it but I thought it would be interesting to see what people had to say about it.
Wow, man. I'd love to send you thousands of dollars because this is so damn cool.
Great. Send whatever you want (except checks drawn on the House of Representatives Bank) to:
Robert Hess
950 Linden, #210
Sunnyvale, CA 94086
CIS: 74660,612
AOL: RHessJr
Internet: 74660.612@compuserve.com
I'd especially like to get suggestions on how to improve this, both code-wise and feature-wise.
Changes implemented 03/18/92 (Version 2)
****************************************
BUG FIX: I left out a closing parenthesis on the first version. It's in now.
I went ahead and stuck in the large layout mentioned above. Nothing changes on how you call CCL. If there are more than 13 items in aList and the user's screen is at least 455 pixels tall, CCL will use a double-height window automatically. The taller window operates exactly the same as the normal-height window.
I changed the name of the layout from ChoiceListDemo to ChoiceListSmall. The taller one is ChoiceListLarge. This doesn't affect you if you're using my ShowChoiceList procedure since I changed the names there for you.
NEW FEATURE: the ShowChoiceList procedure now accept two new parameters (as parameters 3 and 6). In each you can put the name of the procedure to be executed when the user clicks that button. I do a simple "EXECUTE(x)" on the value you pass me, so there's no guarantee that it will work (if you pass a bad value). If you pass me nothing at all, I act exactly how I used to: I close the CCL and pass you the number of the button clicked. If you look at the example procedure "ButtonProc" you will see that you are asked to set two global variables (I have to use globals since EXECUTE returns no values): gBtnRtnCls (which is a boolean; "TRUE" means "when I return, close the CCL", "FALSE" means "when I return, stay in the CCL") and gBtnRtnVal (which is what you want passed back to ShowChoiceList's calling procedure; this is what is usually contained in aList; in other words, you can put a value in gBtnRtnVal and "TRUE" in gBtnRtnCls and the CCL will be closed for you, with gBtnRtnVal passed back to the original calling procedure as though the user had clicked on that value…in my example, I simply pass back the button number clicked). THIS NEW FEATURE CHANGED THE MANNER IN WHICH "ShowChoiceList" IS CALLED. TWO NEW PARAMETERS HAVE BEEN ADDED. SEE THE COMMENTS IN THE CODE ON HOW TO USE THIS NEW VERSION. (I could have appended the new parameters onto the end and done a "Count Parameters" but this is better because no one has to upgrade to this version and everyone should be moving ShowChoiceList into their structure, anyway. It's really more for future users than past ones.)
NEW FEATURE: Instead of having the buttons default to "Cancel" if you don't pass me some text for a button (which was an ugly way to handle it), I now make the button invisible if there's no button text AND the button is disabled. This means that it is possible to have an enabled button which actually has no text inside it. I can't think of an occasion when you would want to do this, but I'm letting you do it anyway.
Changes implemented 03/18/92 (Version 3)
****************************************
I figured that people could handle character referencing (using the "≤" and "≥" symbols instead of "substring"), so I implemented it in the HandleKeyDown proc. I cannot see any difference, even with a huge list, but it's better programmer (albeit less comprehensible to most people).
BUG FIX: it was possible to click on the white space immediately below the last item in the list (but above the button area); this would kick you out of the layout without a selection. This is fixed; if you do it now, nothing happens (no choice, valid or otherwise, is inferred).
NEW FEATURE: Arrow keys move the currently-selected item in the list. Up-arrow and Left-arrow move backwards/up, Down-arrow or and Right-arrow move forwards/down.
ADDITION: I went ahead and implemented the number keys for you. Therefore, typing both numbers and letters makes a selection.
CHANGE: I was setting aFiller for 4D (which does this already since aFiller is grouped with aList) since it seemed to blacken aFiller quicker. This was some goofy optical illusion, so I quit manually setting aFiller. Actually, I ended up completely giving up on the use of aFiller. When I originally designed the layout, I wanted to move the members of the array over a couple of pixels just like 4D does. I could have moved the scrollable area over itself but then highlighting a member would mean that the blackened area wouldn't stretch to the left edge of the screen. So I added the 2-pixel scrollable area and grouped it with aList; that way, when I set a member of aList, aFiller would follow. This worked but it looked like crap; obviously Laurent does some cool offscreen drawing when you click on a scrollable area's member so that it completely darkens immediately; when you set a member yourself, there's a slight (but easily noticeable) pause. SO…now, instead of putting in a tiny grouped scrollable area, I simply prefix each member of aList with a space; when I pass back the selected member, I cut off the space. This looks a lot better and runs just fine. But it's something I hadn't heard anyone mention before…ah, well. Live and learn.
Changes 03/19/92 (version 4)
****************************
NEW FEATURE: I implemented the Home, End, Page Up and Page Down keys for no reason whatsoever…I'm waiting on a compilation, so sue me. They do exactly what you would expect. By the way, they are only implemented in the Tall window since they don't make sense in context of the short window (it's not supposed to be scrollable, remember?).
ADDITION: In the runtime environment, there are now separate menu commands for testing the Tall and Short windows (basically, Tall passes a long array to ShowCHoiceList while Short passes it a short array).
By the way...Jeff West at ACIUS (a close personal fiend) has pointed out that I could have used a 1 pixel by 1 pixel off-screen enterable field to emulate what I am doing with buttons. This is true. But it doesn't let us do the really cool stuff, with which he agrees. So we'll keep doing this nasty buttons-from-hell stuff, OK? Thanks, Jeff (who knows far too much for a mere carbon-based unit).
Changes 03/23/92 (version 5)
****************************
CHANGE: the window type is now 4, which isn't resizeable. Thanks to Dave Batton for pointing this out.
CHANGE: The version number appears in the title of the choice list window. The value is set in Startup, which didn't exist before now.
By the way, in case you haven't figured it out, to use all of this all you need is the Global Proc "ShowChoiceList" and the two layouts in the [File1] ChoiceListSmall and ChoiceListLarge. The other stuff in the struct is purely for demonstration of the CCLD's functionality.
